QuickTime 4 Reference

Using a Polygon Tween Component

A polygon tweener maps a four-sided polygon, such as the boundary of a sprite or track, into another. It can be used to create perspective effects, in which the shape of the destination polygon changes over time. The range of polygons into which the source polygon is mapped is defined by two additional four-sided polygons, which are interpolated to specify a destination polygon for any time point in the tween duration.

To use a polygon tween component (of type kTweenTypePolygon ), do the following:

Create a QT atom container.
Insert a kTweenEntry atom into the QT atom container for the tween.
Insert a kTweenType atom that specifies the tween type into the kTweenEntry atom.
Insert a kTweenData atom into the kTweenEntry atom.

The data is an array of 27 fixed-point values ( Fixed[27] that specifies the three four-sided polygons. Each polygon is specified by 9 consecutive array elements. The first element is each set of 9 contains the number of points used to specify the polygon; this value is coerced to a long integer, and it must always be 4 after coercion. The following 8 values in each set of nine are four x, y pairs that specify the corners of the polygon.

The first set of 9 elements specifies the dimensions of a sprite or track to be mapped. For example, if the object is a sprite, the four points are (0,0) , (spriteWidth, 0) , (spriteWidth, spriteHeight) , (0, spriteHeight). The next set of 9 elements specifies the initial polygon into which the sprite or track is mapped. The next set of 9 elements specifies the final polygon into which the sprite or track is mapped.

The output is a MatrixRecord data structure that you use to map the sprite or track into a four-sided polygon.

Listing 8 shows how to create a polygon tween.

Listing 8 Creating a polygon tween container



 
OSErr CreateSamplePolygonTweenContainer( QTAtomContainer container,

    TimeValue duration, QTAtom *newTweenAtom )

{

    OSErr           err = noErr;

    TimeValue       offset;

    Handle          thePolygonData = nil;

    QTAtom          tweenAtom;

    

    err = QTRemoveChildren( container, kParentAtomIsContainer );

    if ( err ) goto bail;



    offset = 0;

    err = AddTweenAtom( container, kParentAtomIsContainer, 1,

                        kTweenTypePolygon, offset, duration, 0, 0, 

                        nil, &tweenAtom );

    if ( err ) goto bail;

                    

    thePolygonData = CreateSamplePolygonData();

    if ( thePolygonData == nil ) { err = memFullErr; goto bail; }

    

    HLock( thePolygonData );

    

    err = AddDataAtom( container, tweenAtom, 1, 

                        GetHandleSize( thePolygonData ), 

                        *thePolygonData, nil, 0, nil );

    if ( err ) goto bail;



bail:

    if ( thePolygonData ) DisposeHandle( thePolygonData );

    if ( newTweenAtom ) *newTweenAtom = tweenAtom;

    return err;

}



Handle CreateSamplePolygonData( void )

{

    OSErr       err = noErr;

    Handle      polygonData;

    Fixed       *poly;



    polygonData = NewHandle( 27 * sizeof(Fixed) );

    if ( polygonData == nil ) { err = memFullErr; goto bail; }

    

    poly = (Fixed *)*polygonData;

    

    poly[0] = EndianU32_NtoB(4);                // source dimensions

    poly[1] = EndianU32_NtoB(Long2Fix( 0 ));

    poly[2] = EndianU32_NtoB(Long2Fix( 0 ));

    poly[3] = EndianU32_NtoB(Long2Fix( 100 ));

    poly[4] = EndianU32_NtoB(Long2Fix( 0 ));

    poly[5] = EndianU32_NtoB(Long2Fix( 100 ));

    poly[6] = EndianU32_NtoB(Long2Fix( 100 ));

    poly[7] = EndianU32_NtoB(Long2Fix( 0 ));

    poly[8] = EndianU32_NtoB(Long2Fix( 100 ));



    poly[9] = EndianU32_NtoB(4);                // tween from polygon

    poly[10] = EndianU32_NtoB(Long2Fix( 100 ));

    poly[11] = EndianU32_NtoB(Long2Fix( 100 ));

    poly[12] = EndianU32_NtoB(Long2Fix( 200 ));

    poly[13] = EndianU32_NtoB(Long2Fix( 100 ));

    poly[14] = EndianU32_NtoB(Long2Fix( 200 ));

    poly[15] = EndianU32_NtoB(Long2Fix( 200 ));

    poly[16] = EndianU32_NtoB(Long2Fix( 100 ));

    poly[17] = EndianU32_NtoB(Long2Fix( 200 ));



    poly[18] = EndianU32_NtoB(4);               // tween to polygon

    poly[19] = EndianU32_NtoB(Long2Fix( 140 ));

    poly[20] = EndianU32_NtoB(Long2Fix( 100 ));

    poly[21] = EndianU32_NtoB(Long2Fix( 160 ));

    poly[22] = EndianU32_NtoB(Long2Fix( 100 ));

    poly[23] = EndianU32_NtoB(Long2Fix( 200 ));

    poly[24] = EndianU32_NtoB(Long2Fix( 200 ));

    poly[25] = EndianU32_NtoB(Long2Fix( 100 ));

    poly[26] = EndianU32_NtoB(Long2Fix( 200 ));



bail:

    return polygonData;

}